Versioned documenation hosting #104

yardasol · 2022-01-19T21:29:21Z

Summary of changes

This PR enables versioned documentation on the github pages website. You'll need to clone the repo and build the website yourself using the included doc_environment.yml file to get all the necessary packages.

Specifically, this PR

Splits the monolithic environment.yml file into a build/test verison (environment.yml) and a documentation version (doc/doc_environment.yml), and use each in their respective workflow
Adds the sphinx-multiversion and sphinxcontib-apidoc packages to the conda environment in the deploy-docs workflow
Adds configuration options for the above packages to doc/conf.py
Updates the instructions to build the docs in the readme using the new doc/conf.py file.
Adds an html sidebar template for a read-the-docs style version selection menu (doc/_templates/versions.html)
Tightens up the triggers for our workflows:
- deploy-docs now can be triggered by releases
- cache-dependencies now makes separate dependency caches for the new environment.yml dependencies and the doc_environment.yml dependencies.
- test-saltproc now only runs when pushes to the source code and tests are made.
Adds manual triggers for all workflows.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Required for Merging

I have read the CONTRIBUTING document.
My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have added tests to cover my changes.
All new and existing tests passed.
- CI tests pass
- Local tests pass (including Serpent2 integration tests)

Associated Issues and PRs

Issue: closes Feature: Add versioned documentation #102
Issue: closes do not merge any PRs after #95 until a versioned documentation is set up #103
Issue: closes if we end up seeing long build times, we can have a test_environment.yml and a docs_environment.yml file separately and use them in the different builds. #107
PR 62 in sphinx-multiversion was useful in getting things to work, althought I didn't end up actually using that version of the code.

Associated Developers

Dev: @munkm

Checklist for Reviewers

Reviewers should use this link to get to the
Review Checklist before they begin their review.

pep8speaks · 2022-01-19T21:29:24Z

Hello @yardasol! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

In the file doc/conf.py:

Line 23:1: E402 module level import not at top of file

Comment last updated at 2022-01-28 22:52:32 UTC

This reverts commit cea25ad.

This reverts commit 061c29f.

yardasol · 2022-01-27T18:45:43Z

@pep8speaks is saying that the from saltproc.version import __version__ statment needs to be at the top of the file, but we need to add saltproc to the syspath before we are able to execute tthe statement!

LukeSeifert · 2022-01-28T20:02:28Z

I'm not familiar with YAML, but the code looks good to me. However, when I tried following the build directions given in the readme, I got an error. When I changed to the master branch and followed those directions, I did not get an error and was able to build successfully. I included the error message I got here:

Running Sphinx v2.4.0

Extension error:
Could not import extension sphinxcontrib.apidoc (exception: No module named 'sphinxcontrib.apidoc')
Makefile:53: recipe for target 'html' failed
make: *** [html] Error 2

yardasol · 2022-01-28T21:05:24Z

@LukeSeifert Did you make a conda environment from the doc-environent.yml file? Regardless, I think I do need to specify that user's will need to install the conda environment to build the docs.

yardasol · 2022-01-28T21:30:51Z

@munkm is the language I use to describe conda vs mamba appropriate and neutral? Don't want to ruffle any feathers...

yardasol · 2022-01-28T21:31:40Z

@LukeSeifert I changed the instructions. Could you try it again and let me know?

munkm

A few minor comments!

.github/workflows/cache-dependencies.yml

doc/doc-environment.yml

doc/installation.rst

munkm · 2022-01-28T21:56:23Z

README.md


 After these steps, the website will be found in `saltproc/doc/_build/html`.

+_Note_: We recommend using [`mamba`](https://github.com/mamba-org/mamba) CLI tool to install packages quickly. SaltProc has a compltex package dependency structure which can result is long environment solve times in the default ``conda`` solver. ``mamba`` is a reimplementation of ``conda`` in ``C++`` and we have found it is significantly faster.


For the future, you can import the readme in the docs so that you don't have to repeat the same info twice. That way both don't need to be updated if something changes.

The formatting for the .rst files and the .md files is slightly different. I'll need to think of a solution to this later.

munkm · 2022-01-28T21:57:53Z

README.md

-following steps
+The entire contents of that
+website can be built from the `doc` directory in the repositiory using
+the following steps


There are a few other env tools that exist. You should be explicit here that these directions are assuming a conda environment and we haven't tried it with another manager (and don't necessarily recommend it).

.github/workflows/deploy-docs.yml

doc/installation.rst

munkm · 2022-01-28T21:59:57Z

doc/installation.rst

+
+Once all the dependencies are installed, SaltProc can be installed by
+running the following commands from within the cloned directory
+repository:


Suggested change

repository:

repository (and assuming the environment has been activated):

munkm · 2022-01-28T22:01:26Z

saltproc/version.py

@@ -71,7 +72,7 @@

 NAME = "saltproc"
 MAINTAINER = "Oleksandr Yardas"
-MAINTAINER_EMAIL = "[email protected]"
+MAINTAINER_EMAIL = "[email protected]"


are you sure you want all messages to go to your personal email? We could make a mailing list.

Let's make a mailing list. I'll revert back to the googlegroups email here

munkm · 2022-01-28T22:17:07Z

@munkm is the language I use to describe conda vs mamba appropriate and neutral? Don't want to ruffle any feathers...

Yes I think your language is good!

Versioned documenation hosting 66bbd90

yardasol added 9 commits December 13, 2021 11:50

Merge remote-tracking branch 'upstream/master'

74a1140

Merge remote-tracking branch 'origin/master'

d66a31f

inital version of .readthedocs.yaml

07f5baa

update environent.yml

17f1133

add mambaforge

1320f0b

add fail on warning for sphinx option

e95095a

add pip deps to environment file

100afd4

add correct version in sphinx config

361b0d6

make versions consistent

c18e393

yardasol and others added 20 commits January 19, 2022 15:29

add new dependencies to installation page

b9ae15b

update installation instructions

a4fbd6c

typo fix in .readthedocs.yaml

7bc7e88

try adding python

e62483e

doc->docs

cea25ad

doc->docs

061c29f

try disabling sphinx fail_on_error

480be71

remove cruft from docs/src

e98049d

remove crift from integration tests

539e614

fix merge conflict

f6a4bf2

Revert "doc->docs"

5c41d58

This reverts commit cea25ad.

Revert "doc->docs"

446dd53

This reverts commit 061c29f.

created doc-environment.yml

4fe57be

env typo fix

e4c6aff

update doc-environment.yml

cfc6157

update doc-environment.yml

3a7f111

add sphinx_multiversion to conf.py

bb63eb9

update doc-environment.yml

392d0a4

add _templates/versions.html

0bb73ba

add conf settigns for sphinx-multiverison'

cd3b2fe

add explanation comment

415e8ea

yardasol marked this pull request as ready for review January 27, 2022 18:44

yardasol requested a review from munkm January 27, 2022 18:44

yardasol requested review from gwenchee, smpark7 and LukeSeifert January 28, 2022 16:44

yardasol mentioned this pull request Jan 28, 2022

Prepare Simulation and App classes for OpenMC support, rework input file structure #98

Merged

15 tasks

update descriptions in version.py

7cc11b7

yardasol added 4 commits January 28, 2022 15:07

update readme instructions

f67358d

update install instructions in docs

552b922

add note on using mamba

679187c

add mamba blurb to readme

e980a3b

munkm approved these changes Jan 28, 2022

View reviewed changes

yardasol mentioned this pull request Jan 28, 2022

For the future, you can import the readme in the docs so that you don't have to repeat the same info twice. That way both don't need to be updated if something changes. #113

Open

yardasol added 3 commits January 28, 2022 16:46

README.md

9967207

added @munkm suggestions

44bf02a

update maintainer email

9f31ce4

yardasol requested a review from munkm January 28, 2022 22:55

munkm merged commit 66bbd90 into arfc:master Jan 28, 2022

github-actions bot pushed a commit that referenced this pull request Jan 28, 2022

update docs at commit: Merge pull request #104 from yardasol/vc-docs

e89e686

Versioned documenation hosting 66bbd90

yardasol removed the Status:5-In Review label Jan 28, 2022

yardasol deleted the vc-docs branch March 9, 2022 19:00

yardasol restored the vc-docs branch March 9, 2022 19:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Versioned documenation hosting #104

Versioned documenation hosting #104

yardasol commented Jan 19, 2022 •

edited

Loading

pep8speaks commented Jan 19, 2022 •

edited

Loading

yardasol commented Jan 27, 2022

LukeSeifert commented Jan 28, 2022

yardasol commented Jan 28, 2022 •

edited

Loading

yardasol commented Jan 28, 2022

yardasol commented Jan 28, 2022

munkm left a comment

munkm Jan 28, 2022

yardasol Jan 28, 2022

munkm Jan 28, 2022

munkm Jan 28, 2022

munkm Jan 28, 2022

yardasol Jan 28, 2022

munkm commented Jan 28, 2022 •

edited

Loading


		After these steps, the website will be found in `saltproc/doc/_build/html`.

		_Note_: We recommend using [`mamba`](https://github.com/mamba-org/mamba) CLI tool to install packages quickly. SaltProc has a compltex package dependency structure which can result is long environment solve times in the default ``conda`` solver. ``mamba`` is a reimplementation of ``conda`` in ``C++`` and we have found it is significantly faster.

	repository:
	repository (and assuming the environment has been activated):

Versioned documenation hosting #104

Versioned documenation hosting #104

Conversation

yardasol commented Jan 19, 2022 • edited Loading

Summary of changes

Types of changes

Required for Merging

Associated Issues and PRs

Associated Developers

Checklist for Reviewers

pep8speaks commented Jan 19, 2022 • edited Loading

Comment last updated at 2022-01-28 22:52:32 UTC

yardasol commented Jan 27, 2022

LukeSeifert commented Jan 28, 2022

yardasol commented Jan 28, 2022 • edited Loading

yardasol commented Jan 28, 2022

yardasol commented Jan 28, 2022

munkm left a comment

Choose a reason for hiding this comment

munkm Jan 28, 2022

Choose a reason for hiding this comment

yardasol Jan 28, 2022

Choose a reason for hiding this comment

munkm Jan 28, 2022

Choose a reason for hiding this comment

munkm Jan 28, 2022

Choose a reason for hiding this comment

munkm Jan 28, 2022

Choose a reason for hiding this comment

yardasol Jan 28, 2022

Choose a reason for hiding this comment

munkm commented Jan 28, 2022 • edited Loading

yardasol commented Jan 19, 2022 •

edited

Loading

pep8speaks commented Jan 19, 2022 •

edited

Loading

yardasol commented Jan 28, 2022 •

edited

Loading

munkm commented Jan 28, 2022 •

edited

Loading